
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_Hans">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>模板 &#8212; Django 3.2.11.dev 文档</title>
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <link rel="index" title="索引" href="../genindex.html" />
    <link rel="search" title="搜索" href="../search.html" />
    <link rel="next" title="基于类的视图" href="class-based-views/index.html" />
    <link rel="prev" title="表单资源（ Media 类）" href="forms/media.html" />



 
<script src="../templatebuiltins.js"></script>
<script>
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);(function($) {
    $(document).ready(function() {
        $(".c-tab-unix").on("click", function() {
            $("section.c-content-unix").show();
            $("section.c-content-win").hide();
            $(".c-tab-unix").prop("checked", true);
        });
        $(".c-tab-win").on("click", function() {
            $("section.c-content-win").show();
            $("section.c-content-unix").hide();
            $(".c-tab-win").prop("checked", true);
        });
    });
})(jQuery);</script>
<link rel="stylesheet" href="../_static/console-tabs.css" type="text/css" />
  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../index.html">Django 3.2.11.dev 文档</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../index.html">Home</a>  |
        <a title="Table of contents" href="../contents.html">Table of contents</a>  |
        <a title="Global index" href="../genindex.html">Index</a>  |
        <a title="Module index" href="../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="forms/media.html" title="表单资源（ &lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;Media&lt;/span&gt;&lt;/code&gt; 类）">previous</a>
     |
    <a href="index.html" title="使用 Django" accesskey="U">up</a>
   |
    <a href="class-based-views/index.html" title="基于类的视图">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="topics-templates">
            
  <div class="section" id="s-module-django.template">
<span id="s-templates"></span><span id="module-django.template"></span><span id="templates"></span><h1>模板<a class="headerlink" href="#module-django.template" title="永久链接至标题">¶</a></h1>
<p>作为一个网络框架，Django 需要一种方便的方式来动态生成 HTML。最常见的方法是依靠模板。一个模板包含了所需 HTML 输出的静态部分，以及一些特殊的语法，描述了如何插入动态内容。关于使用模板创建 HTML 页面的实战例子，请看 <a class="reference internal" href="../intro/tutorial03.html"><span class="doc">教程 3</span></a>。</p>
<p>一个 Django 项目可以配置一个或多个模板引擎（如果你不使用模板，甚至可以不配置模板）。Django 内置了自己的模板系统后端，创造性地称为 Django 模板语言（DTL），以及流行的替代版本 <a class="reference external" href="https://jinja.palletsprojects.com/">Jinja2</a>。其他模板语言的后端可以从第三方获得。你也可以编写自己的自定义后端，参见：<a class="reference internal" href="../howto/custom-template-backend.html"><span class="doc">自定义模板后端</span></a></p>
<p>Django 定义了一个标准的API，用于加载和渲染模板，而不考虑后端。加载包括为给定的标识符找到模板并对其进行预处理，通常是将其编译成内存中的表示形式。渲染是指将上下文数据插入模板，并返回结果字符串。</p>
<p><a class="reference internal" href="../ref/templates/language.html"><span class="doc">Django 模板语言</span></a> 是 Django 自己的模板系统。在 Django 1.8 之前，它是唯一的内置选项。它是一个很好的模板库，尽管它是相当有主见的，并且有一些特殊的地方。如果你没有迫切的理由选择另一个后端，你应该使用 DTL，特别是当你正在编写一个可插拔的应用程序，并且你打算发布模板时。Django 的 contrib 应用如果包含模板，比如 <a class="reference internal" href="../ref/contrib/admin/index.html"><span class="doc">django.contrib.admin</span></a>，就使用 DTL。</p>
<p>由于历史原因，模板引擎的通用支持和 Django 模板语言的实现都在 <code class="docutils literal notranslate"><span class="pre">django.template</span></code> 的命名空间中。</p>
<div class="admonition warning">
<p class="first admonition-title">警告</p>
<p class="last">模板系统对于不受信任的模板作者并不安全。例如，一个网站不应该允许其用户提供自己的模板，因为模板作者可以做一些事情，如执行 XSS 攻击和访问可能包含敏感信息的模板变量的属性。</p>
</div>
<div class="section" id="s-the-django-template-language">
<span id="s-template-language-intro"></span><span id="the-django-template-language"></span><span id="template-language-intro"></span><h2>Django 模板语言<a class="headerlink" href="#the-django-template-language" title="永久链接至标题">¶</a></h2>
<div class="section" id="s-syntax">
<span id="syntax"></span><h3>语法<a class="headerlink" href="#syntax" title="永久链接至标题">¶</a></h3>
<div class="admonition-about-this-section admonition">
<p class="first admonition-title">关于本节</p>
<p class="last">这是对 Django 模板语言语法的概述。详细信息请参见 <a class="reference internal" href="../ref/templates/language.html"><span class="doc">语言语法参考</span></a>。</p>
</div>
<p>Django 模板是使用 Django 模板语言标记的一个文本文档或Python字符串。模板引擎可以识别和解释一些构造。主要是变量和标签。</p>
<p>模板是通过上下文来渲染的。渲染用变量的值替换变量，变量的值在上下文中查找，并执行标签。其他的一切都按原样输出。</p>
<p>Django 模板语言的语法涉及四个构造。</p>
<div class="section" id="s-variables">
<span id="variables"></span><h4>变量<a class="headerlink" href="#variables" title="永久链接至标题">¶</a></h4>
<p>变量从上下文中输出一个值，上下文是一个类似于字典的对象，将键映射到值。</p>
<p>变量被 <code class="docutils literal notranslate"><span class="pre">{{</span></code> 和 <code class="docutils literal notranslate"><span class="pre">}}</span></code> 包围，如下所示：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>My first name is <span class="cp">{{</span> <span class="nv">first_name</span> <span class="cp">}}</span>. My last name is <span class="cp">{{</span> <span class="nv">last_name</span> <span class="cp">}}</span>.
</pre></div>
</div>
<p>在上下文为 <code class="docutils literal notranslate"><span class="pre">{'first_name':</span> <span class="pre">'John',</span> <span class="pre">'last_name':</span> <span class="pre">'Doe'}</span></code> 的情况下，该模板渲染为：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>My first name is John. My last name is Doe.
</pre></div>
</div>
<p>字典查找，属性查找和列表索引查找均以点符号实现：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">my_dict.key</span> <span class="cp">}}</span>
<span class="cp">{{</span> <span class="nv">my_object.attribute</span> <span class="cp">}}</span>
<span class="cp">{{</span> <span class="nv">my_list.0</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>如果变量解析为可调用对象，则模板系统将不带任何参数的情况下调用它，并使用其结果代替可调用对象。</p>
</div>
<div class="section" id="s-tags">
<span id="tags"></span><h4>标签<a class="headerlink" href="#tags" title="永久链接至标题">¶</a></h4>
<p>标签在渲染过程中提供了任意逻辑。</p>
<p>这个定义是故意含糊的。例如，标签可以输出内容，或用作控制结构如 “if” 语句和 “for” 循环，或从数据库中抓取内容，甚至可以访问其他模板标签。</p>
<p>标签被 <code class="docutils literal notranslate"><span class="pre">{%</span></code> 和 <code class="docutils literal notranslate"><span class="pre">%}</span></code> 包围，如下所示：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">csrf_token</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>大多数标签都接受参数：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">cycle</span> <span class="s1">&#39;odd&#39;</span> <span class="s1">&#39;even&#39;</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>一些标签需要开始和结束标签：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">user.is_authenticated</span> <span class="cp">%}</span>Hello, <span class="cp">{{</span> <span class="nv">user.username</span> <span class="cp">}}</span>.<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>提供 <a class="reference internal" href="../ref/templates/builtins.html#ref-templates-builtins-tags"><span class="std std-ref">内置标签参考</span></a> 以及 <a class="reference internal" href="../howto/custom-template-tags.html#howto-writing-custom-template-tags"><span class="std std-ref">自定义标签编写指南</span></a>。</p>
</div>
<div class="section" id="s-filters">
<span id="filters"></span><h4>过滤器<a class="headerlink" href="#filters" title="永久链接至标题">¶</a></h4>
<p>过滤器转换变量和标签参数的值。</p>
<p>它们看起来像这样：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">django</span><span class="o">|</span><span class="nf">title</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>在 <code class="docutils literal notranslate"><span class="pre">{'django':</span> <span class="pre">'the</span> <span class="pre">web</span> <span class="pre">framework</span> <span class="pre">for</span> <span class="pre">perfectionists</span> <span class="pre">with</span> <span class="pre">deadlines'}</span></code> 的上下文中，这个模板渲染为：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>The Web Framework For Perfectionists With Deadlines
</pre></div>
</div>
<p>有些过滤器需要一个参数：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">my_date</span><span class="o">|</span><span class="nf">date</span><span class="s2">:&quot;Y-m-d&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>提供 <a class="reference internal" href="../ref/templates/builtins.html#ref-templates-builtins-filters"><span class="std std-ref">内建过滤器参考</span></a> 以及 <a class="reference internal" href="../howto/custom-template-tags.html#howto-writing-custom-template-filters"><span class="std std-ref">自定义过滤器编写指南</span></a>.</p>
</div>
<div class="section" id="s-comments">
<span id="comments"></span><h4>Comments<a class="headerlink" href="#comments" title="永久链接至标题">¶</a></h4>
<p>注释看起来像这样：</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="c">{# this won&#39;t be rendered #}</span>
</pre></div>
</div>
<p><a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-comment"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></code></a> 标签提供多行注释。</p>
</div>
</div>
<div class="section" id="s-components">
<span id="components"></span><h3>组件<a class="headerlink" href="#components" title="永久链接至标题">¶</a></h3>
<div class="admonition-about-this-section admonition">
<p class="first admonition-title">关于本节</p>
<p class="last">这是对 Django 模板语言 API 的概述。详细信息请参见 <a class="reference internal" href="../ref/templates/api.html"><span class="doc">API 参考</span></a>。</p>
</div>
<div class="section" id="s-engine">
<span id="engine"></span><h4>引擎<a class="headerlink" href="#engine" title="永久链接至标题">¶</a></h4>
<p><a class="reference internal" href="../ref/templates/api.html#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.Engine</span></code></a> 封装了 Django 模板系统的实例。直接实例化 <a class="reference internal" href="../ref/templates/api.html#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> 的主要原因是为了在 Django 项目之外使用 Django 模板语言。</p>
<p><a class="reference internal" href="#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.backends.django.DjangoTemplates</span></code></a> 是一个简单封装，使 <a class="reference internal" href="../ref/templates/api.html#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.Engine</span></code></a> 适应 Django 的模板后端API。</p>
</div>
<div class="section" id="s-template">
<span id="template"></span><h4>模板<a class="headerlink" href="#template" title="永久链接至标题">¶</a></h4>
<p><a class="reference internal" href="../ref/templates/api.html#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.Template</span></code></a> 代表已编译的模板。模板可以通过 <a class="reference internal" href="../ref/templates/api.html#django.template.Engine.get_template" title="django.template.Engine.get_template"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.get_template()</span></code></a> 或 <a class="reference internal" href="../ref/templates/api.html#django.template.Engine.from_string" title="django.template.Engine.from_string"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.from_string()</span></code></a> 获得。</p>
<p>同样 <code class="docutils literal notranslate"><span class="pre">django.template.backends.django.Template</span></code> 是一个简单封装，使 <a class="reference internal" href="../ref/templates/api.html#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.Template</span></code></a> 适应通用模板 API。</p>
</div>
<div class="section" id="s-context">
<span id="context"></span><h4>上下文<a class="headerlink" href="#context" title="永久链接至标题">¶</a></h4>
<p><a class="reference internal" href="../ref/templates/api.html#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.Context</span></code></a> 除了上下文数据外，还保存了一些元数据。它被传递给 <a class="reference internal" href="../ref/templates/api.html#django.template.Template.render" title="django.template.Template.render"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Template.render()</span></code></a> 来渲染模板。</p>
<p><a class="reference internal" href="../ref/templates/api.html#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.RequestContext</span></code></a> 是 <a class="reference internal" href="../ref/templates/api.html#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> 的子类，它储存当前的 <a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> 并运行模板上下文处理器。</p>
<p>通用 API 没有对应的概念。上下文数据以普通的 <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(在 Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> 传递，而当前的 <a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> 则根据需要单独传递。</p>
</div>
<div class="section" id="s-loaders">
<span id="loaders"></span><h4>加载器<a class="headerlink" href="#loaders" title="永久链接至标题">¶</a></h4>
<p>模板加载器负责定位模板，加载模板，并返回 <a class="reference internal" href="../ref/templates/api.html#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> 对象。</p>
<p>Django 提供了几个 <a class="reference internal" href="../ref/templates/api.html#template-loaders"><span class="std std-ref">内建模板加载器</span></a> 并且支持 <a class="reference internal" href="../ref/templates/api.html#custom-template-loaders"><span class="std std-ref">自定义模板加载器</span></a>。</p>
</div>
<div class="section" id="s-context-processors">
<span id="context-processors"></span><h4>上下文处理器<a class="headerlink" href="#context-processors" title="永久链接至标题">¶</a></h4>
<p>上下文处理器是接收当前的 <a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> 作为参数，并返回一个 <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(在 Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> 的数据添加到渲染上下文的函数。</p>
<p>它们的主要用途是将所有模板共享的通用数据添加到上下文中，而无需在每个视图中重复代码。</p>
<p>Django 提供了许多 <a class="reference internal" href="../ref/templates/api.html#context-processors"><span class="std std-ref">内置上下文处理器</span></a>，你也可以实现自己的其他上下文处理器。</p>
</div>
</div>
</div>
<div class="section" id="s-support-for-template-engines">
<span id="s-template-engines"></span><span id="support-for-template-engines"></span><span id="template-engines"></span><h2>模板引擎的支持<a class="headerlink" href="#support-for-template-engines" title="永久链接至标题">¶</a></h2>
<div class="section" id="s-configuration">
<span id="configuration"></span><h3>配置<a class="headerlink" href="#configuration" title="永久链接至标题">¶</a></h3>
<p>模板引擎是通过 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> 进行配置。这是一个配置列表，每个引擎都有一个。默认值为空。<a class="reference internal" href="../ref/django-admin.html#django-admin-startproject"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">startproject</span></code></a> 命令生成的 <code class="docutils literal notranslate"><span class="pre">settings.py</span></code>  定义了一个更有用的值：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">{</span>
        <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
        <span class="s1">&#39;DIRS&#39;</span><span class="p">:</span> <span class="p">[],</span>
        <span class="s1">&#39;APP_DIRS&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
        <span class="s1">&#39;OPTIONS&#39;</span><span class="p">:</span> <span class="p">{</span>
            <span class="c1"># ... some options here ...</span>
        <span class="p">},</span>
    <span class="p">},</span>
<span class="p">]</span>
</pre></div>
</div>
<p><a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-BACKEND"><code class="xref std std-setting docutils literal notranslate"><span class="pre">BACKEND</span></code></a> 是实现 Django 模板后端 API 的模板引擎类的点分隔 Python 路径。内置的后端有 <a class="reference internal" href="#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.backends.django.DjangoTemplates</span></code></a> 和 <a class="reference internal" href="#django.template.backends.jinja2.Jinja2" title="django.template.backends.jinja2.Jinja2"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.backends.jinja2.Jinja2</span></code></a>。</p>
<p>由于大多数引擎都是从文件中加载模板，因此每个引擎的顶层配置都包含两个常见的配置：</p>
<ul class="simple">
<li><a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> 定义了目录列表，引擎应在其中按搜索顺序查找模板源文件。</li>
<li><a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">APP_DIRS</span></code></a> 告诉引擎是否应该在已安装的应用程序中寻找模板。每个后端都为应用程序中存储模板的子目录定义了一个惯用名称。</li>
</ul>
<p>虽然不常见，但可以使用不同的选项配置同一后端的多个实例。 在这种情况下，你应该为每个引擎定义一个唯一的 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-NAME"><code class="xref std std-setting docutils literal notranslate"><span class="pre">NAME</span></code></a>。</p>
<p><a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-OPTIONS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">OPTIONS</span></code></a> 包含特定于后端的配置。</p>
</div>
<div class="section" id="s-module-django.template.loader">
<span id="s-usage"></span><span id="s-template-loading"></span><span id="module-django.template.loader"></span><span id="usage"></span><span id="template-loading"></span><h3>用法<a class="headerlink" href="#module-django.template.loader" title="永久链接至标题">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">django.template.loader</span></code> 模块定义了两个加载模板的函数。</p>
<dl class="function">
<dt id="django.template.loader.get_template">
<code class="descname">get_template</code>(<em>template_name</em>, <em>using=None</em>)<a class="headerlink" href="#django.template.loader.get_template" title="永久链接至目标">¶</a></dt>
<dd><p>此函数使用给定名称加载模板并返回 <code class="docutils literal notranslate"><span class="pre">Template</span></code> 对象。</p>
<p>返回值的确切类型取决于加载模板的后端。 每个后端都有自己的 <code class="docutils literal notranslate"><span class="pre">Template</span></code> 类。</p>
<p><code class="docutils literal notranslate"><span class="pre">get_template()</span></code> 依次尝试每个模板引擎，直到成功为止。如果找不到模板，则会引发 <a class="reference internal" href="#django.template.TemplateDoesNotExist" title="django.template.TemplateDoesNotExist"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TemplateDoesNotExist</span></code></a> 错误。如果找到模板但包含无效语法，则会引发 <a class="reference internal" href="#django.template.TemplateSyntaxError" title="django.template.TemplateSyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TemplateSyntaxError</span></code></a> 错误。</p>
<p>搜索和加载模板的方式取决于每个引擎的后端和配置。</p>
<p>如果你想把搜索限制在一个特定的模板引擎上，在 <code class="docutils literal notranslate"><span class="pre">using</span></code> 参数中传递该引擎的 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-NAME"><code class="xref std std-setting docutils literal notranslate"><span class="pre">NAME</span></code></a>。</p>
</dd></dl>

<dl class="function">
<dt id="django.template.loader.select_template">
<code class="descname">select_template</code>(<em>template_name_list</em>, <em>using=None</em>)<a class="headerlink" href="#django.template.loader.select_template" title="永久链接至目标">¶</a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">select_template()</span></code> 就像 <code class="docutils literal notranslate"><span class="pre">get_template()</span></code>，不同的是，它接受一个模板名称的列表。它按顺序尝试每个名字，并返回第一个存在的模板。</p>
</dd></dl>

<p>如果加载模板失败，则可能会引发在 <code class="docutils literal notranslate"><span class="pre">django.template</span></code> 中定义的以下两个异常：</p>
<dl class="exception">
<dt id="django.template.TemplateDoesNotExist">
<em class="property">exception </em><code class="descname">TemplateDoesNotExist</code>(<em>msg</em>, <em>tried=None</em>, <em>backend=None</em>, <em>chain=None</em>)<a class="headerlink" href="#django.template.TemplateDoesNotExist" title="永久链接至目标">¶</a></dt>
<dd><p>当找不到模板时引发此异常。 它接受以下可选参数在调试页面上填充 <a class="reference internal" href="../howto/custom-template-backend.html#template-postmortem"><span class="std std-ref">模板事后检验</span></a> ：</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">backend</span></code></dt>
<dd>产生异常的模板后端实例。</dd>
<dt><code class="docutils literal notranslate"><span class="pre">tried</span></code></dt>
<dd>查找模板时尝试过的来源列表。它的格式为包含 <code class="docutils literal notranslate"><span class="pre">(origin,</span> <span class="pre">status)</span></code> 的元组列表，其中 <code class="docutils literal notranslate"><span class="pre">origin</span></code> 是一个 <a class="reference internal" href="../howto/custom-template-backend.html#template-origin-api"><span class="std std-ref">类 origin</span></a> 对象而 <code class="docutils literal notranslate"><span class="pre">status</span></code> 是一个说明找不到模板原因的字符串。</dd>
<dt><code class="docutils literal notranslate"><span class="pre">chain</span></code></dt>
<dd>尝试加载模板时引发的一系列中间 <a class="reference internal" href="#django.template.TemplateDoesNotExist" title="django.template.TemplateDoesNotExist"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TemplateDoesNotExist</span></code></a> 异常列表。这由函数使用，例如：<a class="reference internal" href="#django.template.loader.get_template" title="django.template.loader.get_template"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_template()</span></code></a>，这些函数尝试从多个引擎加载给定的模板。</dd>
</dl>
</dd></dl>

<dl class="exception">
<dt id="django.template.TemplateSyntaxError">
<em class="property">exception </em><code class="descname">TemplateSyntaxError</code>(<em>msg</em>)<a class="headerlink" href="#django.template.TemplateSyntaxError" title="永久链接至目标">¶</a></dt>
<dd><p>当找到模板但包含错误时，将引发此异常。</p>
</dd></dl>

<p>由 <code class="docutils literal notranslate"><span class="pre">get_template()</span></code> 和 <code class="docutils literal notranslate"><span class="pre">select_template()</span></code> 返回的 <code class="docutils literal notranslate"><span class="pre">Template</span></code> 对象必须提供具有以下签名的 <cite>render()`</cite> 方法：</p>
<dl class="method">
<dt id="django.template.backends.base.Template.render">
<code class="descclassname">Template.</code><code class="descname">render</code>(<em>context=None</em>, <em>request=None</em>)<a class="headerlink" href="#django.template.backends.base.Template.render" title="永久链接至目标">¶</a></dt>
<dd><p>使用给定的上下文渲染此模板。</p>
<p>如果提供了 <code class="docutils literal notranslate"><span class="pre">context</span></code> ，则必须是 <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(在 Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>。如果未提供，则引擎将使用空上下文渲染模板。</p>
<p>如果提供了 <code class="docutils literal notranslate"><span class="pre">request</span></code>，它必须是 <a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a>。同时引擎必须使它和 CSRF 令牌在模板中可用。如何实现这一点由每个后端决定。</p>
</dd></dl>

<p>下面是一个搜索算法的例子。在这个例子中 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> 设置为：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">{</span>
        <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
        <span class="s1">&#39;DIRS&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;/home/html/example.com&#39;</span><span class="p">,</span>
            <span class="s1">&#39;/home/html/default&#39;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
    <span class="p">{</span>
        <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.jinja2.Jinja2&#39;</span><span class="p">,</span>
        <span class="s1">&#39;DIRS&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;/home/html/jinja2&#39;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">]</span>
</pre></div>
</div>
<p>如果你调用 <code class="docutils literal notranslate"><span class="pre">get_template('story_detail.html')</span></code>，以下是 Django 将按顺序查找的文件：</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">/home/html/example.com/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/default/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/jinja2/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'jinja2'</span></code> 引擎）</li>
</ul>
<p>如果你调用 <code class="docutils literal notranslate"><span class="pre">select_template(['story_253_detail.html',</span> <span class="pre">'story_detail.html'])</span></code>，Django 将寻找以下内容：</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">/home/html/example.com/story_253_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/default/story_253_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/jinja2/story_253_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'jinja2'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/example.com/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/default/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/jinja2/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'jinja2'</span></code> 引擎）</li>
</ul>
<p>当 Django 发现一个模板存在时，它就会停止寻找。</p>
<div class="admonition-tip admonition">
<p class="first admonition-title">提示</p>
<p class="last">你可以使用 <a class="reference internal" href="#django.template.loader.select_template" title="django.template.loader.select_template"><code class="xref py py-func docutils literal notranslate"><span class="pre">select_template()</span></code></a> 灵活的加载模板。例如，如果你写了一个新闻故事，并希望一些故事有自定义模板，使用类似 <code class="docutils literal notranslate"><span class="pre">select_template(['story_%s_detail.html'</span> <span class="pre">%</span> <span class="pre">story.id,</span> <span class="pre">'story_detail.html'])</span></code> 。这将允许你为单个故事使用自定义模板，为没有自定义模板的故事使用备用模板。</p>
</div>
<p>可以——而且最好是——在每个包含模板的目录内的子目录中组织模板。惯例是为每个 Django 应用程序创建一个子目录，根据需要在这些子目录中包含子目录。</p>
<p>这样做是为了你自己的理智。将所有模板存储在一个目录的根级别会很麻烦。</p>
<p>要加载子目录中的模板，请使用斜杠，如下所示：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">get_template</span><span class="p">(</span><span class="s1">&#39;news/story_detail.html&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>使用与上述相同的 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> 选项，这将尝试加载以下模板：</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">/home/html/example.com/news/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/default/news/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'django'</span></code> 引擎）</li>
<li><code class="docutils literal notranslate"><span class="pre">/home/html/jinja2/news/story_detail.html</span></code> （<code class="docutils literal notranslate"><span class="pre">'jinja2'</span></code> 引擎）</li>
</ul>
<p>此外，为了减少加载和渲染模板的重复性，Django 提供了一个自动处理的快捷函数。</p>
<dl class="function">
<dt id="django.template.loader.render_to_string">
<code class="descname">render_to_string</code>(<em>template_name</em>, <em>context=None</em>, <em>request=None</em>, <em>using=None</em>)<a class="headerlink" href="#django.template.loader.render_to_string" title="永久链接至目标">¶</a></dt>
<dd><p><code class="docutils literal notranslate"><span class="pre">render_to_string()</span></code> 加载一个模板 <a class="reference internal" href="#django.template.loader.get_template" title="django.template.loader.get_template"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_template()</span></code></a> ，并立即调用它的 <code class="docutils literal notranslate"><span class="pre">render()</span></code> 方法。它需要下面的参数。</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">template_name</span></code></dt>
<dd>加载和呈现模板的名称。如果是模板名称列表，Django 使用 <a class="reference internal" href="#django.template.loader.select_template" title="django.template.loader.select_template"><code class="xref py py-func docutils literal notranslate"><span class="pre">select_template()</span></code></a> ，而不是 <a class="reference internal" href="#django.template.loader.get_template" title="django.template.loader.get_template"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_template()</span></code></a> 找到模板。</dd>
<dt><code class="docutils literal notranslate"><span class="pre">context</span></code></dt>
<dd>&nbsp;<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(在 Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> 用作模板的渲染上下文。</dd>
<dt><code class="docutils literal notranslate"><span class="pre">request</span></code></dt>
<dd>&nbsp;可选项 <a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> 在模板的渲染过程中可用。</dd>
<dt><code class="docutils literal notranslate"><span class="pre">using</span></code></dt>
<dd>可选的模板引擎 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-NAME"><code class="xref std std-setting docutils literal notranslate"><span class="pre">NAME</span></code></a>。对模板的搜索将限于该引擎。</dd>
</dl>
<p>使用实例：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.template.loader</span> <span class="kn">import</span> <span class="n">render_to_string</span>
<span class="n">rendered</span> <span class="o">=</span> <span class="n">render_to_string</span><span class="p">(</span><span class="s1">&#39;my_template.html&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="s1">&#39;bar&#39;</span><span class="p">})</span>
</pre></div>
</div>
</dd></dl>

<p>还可以参看 <a class="reference internal" href="http/shortcuts.html#django.shortcuts.render" title="django.shortcuts.render"><code class="xref py py-func docutils literal notranslate"><span class="pre">render()</span></code></a> 快捷函数，它调用 <a class="reference internal" href="#django.template.loader.render_to_string" title="django.template.loader.render_to_string"><code class="xref py py-func docutils literal notranslate"><span class="pre">render_to_string()</span></code></a> ，并将结果提供给 <a class="reference internal" href="../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpResponse</span></code></a> ，适合从视图返回。</p>
<p>最后，您可以直接使用配置好的引擎：</p>
<dl class="data">
<dt id="django.template.loader.engines">
<code class="descname">engines</code><a class="headerlink" href="#django.template.loader.engines" title="永久链接至目标">¶</a></dt>
<dd><p>模板引擎可在 <code class="docutils literal notranslate"><span class="pre">django.template.engines</span></code> 中使用：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">engines</span>

<span class="n">django_engine</span> <span class="o">=</span> <span class="n">engines</span><span class="p">[</span><span class="s1">&#39;django&#39;</span><span class="p">]</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">django_engine</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="s2">&quot;Hello {{ name }}!&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>在这个例子中，查找关键字“django”是引擎的 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-NAME"><code class="xref std std-setting docutils literal notranslate"><span class="pre">NAME</span></code></a>。</p>
</dd></dl>

<span class="target" id="module-django.template.backends"></span></div>
<div class="section" id="s-module-django.template.backends.django">
<span id="s-built-in-backends"></span><span id="module-django.template.backends.django"></span><span id="built-in-backends"></span><h3>内置后端<a class="headerlink" href="#module-django.template.backends.django" title="永久链接至标题">¶</a></h3>
<dl class="class">
<dt id="django.template.backends.django.DjangoTemplates">
<em class="property">class </em><code class="descname">DjangoTemplates</code><a class="headerlink" href="#django.template.backends.django.DjangoTemplates" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>设置 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-BACKEND"><code class="xref std std-setting docutils literal notranslate"><span class="pre">BACKEND</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">'django.template.backends.django.DjangoTemplates'</span></code>，以配置 Django 模板引擎。</p>
<p>当 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">APP_DIRS</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 时，<code class="docutils literal notranslate"><span class="pre">DjangoTemplates</span></code> 引擎会在已安装应用程序的 <code class="docutils literal notranslate"><span class="pre">templates</span></code> 子目录中寻找模板。这个通用名称是为了向后兼容而保留的。</p>
<p><code class="docutils literal notranslate"><span class="pre">DjangoTemplates</span></code> 引擎接受以下 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-OPTIONS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">OPTIONS</span></code></a>:</p>
<ul>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'autoescape'</span></code>：一个布尔值，控制是否启用 HTML 自动转义。</p>
<p>默认为 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
<div class="admonition warning">
<p class="first admonition-title">警告</p>
<p class="last">只有当你渲染非 HTML 模板时，才将其设置为 <code class="docutils literal notranslate"><span class="pre">False</span></code>！</p>
</div>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'context_processors'</span></code>：当模板被请求渲染时，用于填充上下文的可调用项的点分隔 Python 路径列表。这些可调用的对象以一个请求对象作为参数，并返回一个 <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(在 Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> 的项目，这些项目将被合并到上下文中。</p>
<p>默认为空列表。</p>
<p>查看 <a class="reference internal" href="../ref/templates/api.html#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestContext</span></code></a> 获取更多信息。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'debug'</span></code>：开启／关闭模板调试模式的布尔值。如果是 <code class="docutils literal notranslate"><span class="pre">True</span></code>，错误页面将显示模板渲染过程中出现的任何异常的详细报告。该报告包含模板的相关片段，并突出显示相应的行。</p>
<p>默认为 <a class="reference internal" href="../ref/settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a> 配置的值。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'loaders'</span></code>：模板加载器类的点分隔 Python 路径列表。每个 <code class="docutils literal notranslate"><span class="pre">Loader</span></code> 类都知道如何从特定源导入模板。可以选择使用元组来代替字符串。元组中的第一项应该是 <code class="docutils literal notranslate"><span class="pre">Loader</span></code> 类名，随后的项在初始化期间传递给 <code class="docutils literal notranslate"><span class="pre">Loader</span></code>。</p>
<p>默认值取决于 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> 和 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">APP_DIRS</span></code></a> 的值。</p>
<p>查看 <a class="reference internal" href="../ref/templates/api.html#template-loaders"><span class="std std-ref">加载器类型</span></a> 获取详细信息。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'string_if_invalid'</span></code>：模板系统对无效变量（如拼写错误）应将此字符串输出。</p>
<p>默认为空字符串。</p>
<p>查看 <a class="reference internal" href="../ref/templates/api.html#invalid-template-variables"><span class="std std-ref">如何处理无效变量</span></a> 获取更多信息。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'file_charset'</span></code>：用于读取磁盘上模板文件的字符集。</p>
<p>默认为 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'libraries'</span></code>：模板标签模块的标签字典和点分隔 Python 路径，用于向模板引擎注册。 这可用于添加新库或为现有库提供替代标签。例如：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">OPTIONS</span><span class="o">=</span><span class="p">{</span>
    <span class="s1">&#39;libraries&#39;</span><span class="p">:</span> <span class="p">{</span>
        <span class="s1">&#39;myapp_tags&#39;</span><span class="p">:</span> <span class="s1">&#39;path.to.myapp.tags&#39;</span><span class="p">,</span>
        <span class="s1">&#39;admin.urls&#39;</span><span class="p">:</span> <span class="s1">&#39;django.contrib.admin.templatetags.admin_urls&#39;</span><span class="p">,</span>
    <span class="p">},</span>
<span class="p">}</span>
</pre></div>
</div>
<p>可以通过将相应的字典键传递到 <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></code></a> 标签来加载库。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'builtins'</span></code>：要添加的 <a class="reference internal" href="../ref/templates/builtins.html"><span class="doc">内置模板标签和过滤器</span></a> 的点分隔 Python 路径列表。例如：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">OPTIONS</span><span class="o">=</span><span class="p">{</span>
    <span class="s1">&#39;builtins&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;myapp.builtins&#39;</span><span class="p">],</span>
<span class="p">}</span>
</pre></div>
</div>
<p>可以使用内置库中的标签和过滤器，而不需要先调用 <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></code></a> 标签。</p>
</li>
</ul>
<span class="target" id="module-django.template.backends.jinja2"></span><dl class="class">
<dt id="django.template.backends.jinja2.Jinja2">
<em class="property">class </em><code class="descname">Jinja2</code><a class="headerlink" href="#django.template.backends.jinja2.Jinja2" title="永久链接至目标">¶</a></dt>
<dd></dd></dl>

<p>需要安装 <a class="reference external" href="https://jinja.palletsprojects.com/">Jinja2</a>：</p>
<div class="console-block" id="console-block-0">
<input class="c-tab-unix" id="c-tab-0-unix" type="radio" name="console-0" checked>
<label for="c-tab-0-unix" title="Linux/macOS">&#xf17c/&#xf179</label>
<input class="c-tab-win" id="c-tab-0-win" type="radio" name="console-0">
<label for="c-tab-0-win" title="Windows">&#xf17a</label>
<section class="c-content-unix" id="c-content-0-unix">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python -m pip install Jinja2
</pre></div>
</div>
</section>
<section class="c-content-win" id="c-content-0-win">
<div class="highlight"><pre><span></span><span class="gp">...\&gt;</span> py -m pip install Jinja2
</pre></div>
</section>
</div>
<p>设置 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-BACKEND"><code class="xref std std-setting docutils literal notranslate"><span class="pre">BACKEND</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">'django.template.backends.jinja2.Jinja2'</span></code> 以配置一个 <a class="reference external" href="https://jinja.palletsprojects.com/">Jinja2</a> 引擎。</p>
<p>当 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">APP_DIRS</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 时，<code class="docutils literal notranslate"><span class="pre">Jinja2</span></code> 引擎会在安装的应用程序的 <code class="docutils literal notranslate"><span class="pre">jinja2</span></code> 子目录中查找模板。</p>
<p><a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-OPTIONS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">OPTIONS</span></code></a> 中最重要的条目是 <code class="docutils literal notranslate"><span class="pre">'environment'</span></code>。它是一个点分隔 Python 路径，指向一个返回 Jinja2 环境的可调用对象。默认为 <code class="docutils literal notranslate"><span class="pre">'jinja2.Environment'</span></code>。Django 调用该可调用对象并传递其他选项作为关键字参数。此外，Django 为一些选项添加了不同于 Jinja2 的默认值。</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">'autoescape'</span></code>：<code class="docutils literal notranslate"><span class="pre">True</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'loader'</span></code>：为 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> 和 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">APP_DIRS</span></code></a> 配置的加载器</li>
<li><code class="docutils literal notranslate"><span class="pre">'auto_reload'</span></code>：<code class="docutils literal notranslate"><span class="pre">settings.DEBUG</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'undefined'</span></code>：<code class="docutils literal notranslate"><span class="pre">DebugUndefined</span> <span class="pre">if</span> <span class="pre">settings.DEBUG</span> <span class="pre">else</span> <span class="pre">Undefined</span></code></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">Jinja2</span></code> 引擎也接受以下 <a class="reference internal" href="../ref/settings.html#std:setting-TEMPLATES-OPTIONS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">OPTIONS</span></code></a>：</p>
<ul>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'context_processors'</span></code>：当模板被请求渲染时，用于填充上下文的可调用项的点分隔 Python 路径列表。这些可调用的对象以一个请求对象作为参数，并返回一个 <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(在 Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> 的项目，这些项目将被合并到上下文中。</p>
<p>默认为空列表。</p>
<div class="admonition-using-context-processors-with-jinja2-templates-is-discouraged admonition">
<p class="first admonition-title">不建议将上下文处理器与 Jinja2 模板一起使用。</p>
<p>上下文处理器在 Django 模板中很有用，因为 Django 模板不支持调用带参数的函数。由于 Jinja2 没有此限制，因此建议将你要用作上下文处理器的函数放在模板的全局变量 <code class="docutils literal notranslate"><span class="pre">jinja2.Environment</span></code> 中使用，如下所述。然后你可以在模板中调用该函数。</p>
<div class="highlight-jinja notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">function</span><span class="o">(</span><span class="nv">request</span><span class="o">)</span> <span class="cp">}}</span><span class="x"></span>
</pre></div>
</div>
<p>有些 Django 模板的上下文处理器会返回一个固定的值。对于 Jinja2 模板，不需要这一层间接操作，因为您可以直接在 <code class="docutils literal notranslate"><span class="pre">jinja2.Environment</span></code> 中添加常量。</p>
<p>最初为 Jinja2 增加上下文处理器的用例涉及：</p>
<ul class="simple">
<li>根据请求进行昂贵的计算。</li>
<li>在每个模板中都需要结果。</li>
<li>在每个模板中多次使用结果。</li>
</ul>
<p class="last">除非满足所有这些条件，否则将函数传递给模板更符合 Jinja2 的设计。</p>
</div>
</li>
</ul>
<p>默认配置被有意地保持为最低。如果一个模板被请求渲染（例如，当使用 <a class="reference internal" href="http/shortcuts.html#django.shortcuts.render" title="django.shortcuts.render"><code class="xref py py-func docutils literal notranslate"><span class="pre">render()</span></code></a>），<code class="docutils literal notranslate"><span class="pre">Jinja2</span></code> 后端会在上下文中添加 <code class="docutils literal notranslate"><span class="pre">request</span></code>，<code class="docutils literal notranslate"><span class="pre">csrf_input</span></code> 和 <code class="docutils literal notranslate"><span class="pre">csrf_token</span></code>。除此之外，此后端不会创建 Django 风格的环境。 它不知道 Django 过滤器和标签。 为了使用 Django 特有的 API，你必须将它们配置到环境中。</p>
<p>例如，您可以使用以下内容创建 <code class="docutils literal notranslate"><span class="pre">myproject/jinja2.py</span></code> ：</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.templatetags.static</span> <span class="kn">import</span> <span class="n">static</span>
<span class="kn">from</span> <span class="nn">django.urls</span> <span class="kn">import</span> <span class="n">reverse</span>

<span class="kn">from</span> <span class="nn">jinja2</span> <span class="kn">import</span> <span class="n">Environment</span>


<span class="k">def</span> <span class="nf">environment</span><span class="p">(</span><span class="o">**</span><span class="n">options</span><span class="p">):</span>
    <span class="n">env</span> <span class="o">=</span> <span class="n">Environment</span><span class="p">(</span><span class="o">**</span><span class="n">options</span><span class="p">)</span>
    <span class="n">env</span><span class="o">.</span><span class="n">globals</span><span class="o">.</span><span class="n">update</span><span class="p">({</span>
        <span class="s1">&#39;static&#39;</span><span class="p">:</span> <span class="n">static</span><span class="p">,</span>
        <span class="s1">&#39;url&#39;</span><span class="p">:</span> <span class="n">reverse</span><span class="p">,</span>
    <span class="p">})</span>
    <span class="k">return</span> <span class="n">env</span>
</pre></div>
</div>
<p>并将 <code class="docutils literal notranslate"><span class="pre">'environment'</span></code> 选项设置为 <code class="docutils literal notranslate"><span class="pre">'myproject.jinja2.environment'</span></code>。</p>
<p>这样你就可以在 Jinja2 模板中使用以下构造：</p>
<div class="highlight-html+jinja notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">img</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">static</span><span class="o">(</span><span class="s1">&#39;path/to/company-logo.png&#39;</span><span class="o">)</span> <span class="cp">}}</span><span class="s">&quot;</span> <span class="na">alt</span><span class="o">=</span><span class="s">&quot;Company Logo&quot;</span><span class="p">&gt;</span>

<span class="p">&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">url</span><span class="o">(</span><span class="s1">&#39;admin:index&#39;</span><span class="o">)</span> <span class="cp">}}</span><span class="s">&quot;</span><span class="p">&gt;</span>Administration<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Django 模板语言和 Jinja2 中都存在标签和过滤器的概念，但使用方式不同。由于 Jinja2 支持在模板中向可调用对象传递参数，所以很多在 Django 模板中需要模板标签或过滤器的功能都可以通过在 Jinja2 模板中调用函数来实现，如上例所示。Jinja2 的全局命名空间消除了对模板上下文处理器的需求。Django 模板语言并没有与 Jinja2 测试相对应的功能。</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">模板</a><ul>
<li><a class="reference internal" href="#the-django-template-language">Django 模板语言</a><ul>
<li><a class="reference internal" href="#syntax">语法</a><ul>
<li><a class="reference internal" href="#variables">变量</a></li>
<li><a class="reference internal" href="#tags">标签</a></li>
<li><a class="reference internal" href="#filters">过滤器</a></li>
<li><a class="reference internal" href="#comments">Comments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#components">组件</a><ul>
<li><a class="reference internal" href="#engine">引擎</a></li>
<li><a class="reference internal" href="#template">模板</a></li>
<li><a class="reference internal" href="#context">上下文</a></li>
<li><a class="reference internal" href="#loaders">加载器</a></li>
<li><a class="reference internal" href="#context-processors">上下文处理器</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#support-for-template-engines">模板引擎的支持</a><ul>
<li><a class="reference internal" href="#configuration">配置</a></li>
<li><a class="reference internal" href="#module-django.template.loader">用法</a></li>
<li><a class="reference internal" href="#module-django.template.backends.django">内置后端</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>上一个主题</h4>
  <p class="topless"><a href="forms/media.html"
                        title="上一章">表单资源（ <code class="docutils literal notranslate"><span class="pre">Media</span></code> 类）</a></p>
  <h4>下一个主题</h4>
  <p class="topless"><a href="class-based-views/index.html"
                        title="下一章">基于类的视图</a></p>
  <div role="note" aria-label="source link">
    <h3>本页</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/topics/templates.txt"
            rel="nofollow">显示源代码</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>快速搜索</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="转向" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">12月 07, 2021</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="forms/media.html" title="表单资源（ &lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;Media&lt;/span&gt;&lt;/code&gt; 类）">previous</a>
     |
    <a href="index.html" title="使用 Django" accesskey="U">up</a>
   |
    <a href="class-based-views/index.html" title="基于类的视图">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>